Documentação - Documentação

post https://gateway.iugu.com/api/v1/transactions/cancel/{payment_id}

Cancelar um pagamento

Cancela ou reembolsa um pagamento previamente capturado ou autorizado. ──────────────────────────────────────────────────────────────────────────────── CANCELAMENTO TOTAL: Para cancelar o valor total, não envie o parâmetro amount_cents ou envie o valor total do pagamento. ──────────────────────────────────────────────────────────────────────────────── CANCELAMENTO PARCIAL: É possível cancelar parcialmente um pagamento. A soma de todos os cancelamentos não pode exceder o valor original. Autorizações só podem ser canceladas com o valor total (cancelamento parcial não é permitido). ──────────────────────────────────────────────────────────────────────────────── RESTRIÇÕES: Valores devem ser maiores que zero. Limite de taxa: máximo de 1 requisição por hora por payment_id. ──────────────────────────────────────────────────────────────────────────────── POLÍTICAS ESPECÍFICAS POR ADQUIRENTE: - Getnet: Cancelamento parcial no mesmo dia (D0) não é permitido - Outras restrições podem variar por adquirente (Cielo, Rede, Safrapay)

Permissão necessária: gateway:transactions.cancel

Esta permissão deve constar como uma das ações permitidas para o app que faz a chamada. Isto pode ser feito através do GIA, ou então na edição do aplicativo. Em caso de dúvidas, clique aqui.

Request

Path variables
payment_id Required Type: string ID do pagamento a ser cancelado

Body

Content Type: application/json

amount_cents

Integer >= 1

Valor a ser reembolsado em centavos (opcional). Se não informado, cancela o valor total disponível.

Ex: 5000

Example

1
2
3
{
  "amount_cents": 5000
}

Response

200

Pagamento cancelado com sucesso

payment

Object

String

status

String

multi Array of strings

success_ec

String

mcc

String

recurrent

Boolean

card_on_file

String

tid

String

nsu

String

authorization_code

String

amount_cents

Integer

refunded_amount_cents

Integer

cnpj

String

workspace_id

String

account_id

String

invoice_id

String

client_ref

String

credit_card_id

String

currency

String

installments

Integer

soft_descriptor

String

created_at

String

updated_at

String

transactions

Array of objects

function

String

success

Boolean

tid

String

nsu

String

arp

String

acquirer

Object

payment_id

String

status_code

String

acquirer_mac_code

String

status_description

String

request_status_code

String

request_status_description

String

card_on_file

String

amount_cents

Integer

commercial_enterprise

Object

String

name

String

number

String

acquirer

String

mcc

Object

String

code

String

description

String

created_at

String

anti_fraud

Array of objects

String

status

String

score

Integer

created_at

String

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
{
  "payment": {
    "id": "<ID>",
    "status": "<STATUS>",
    "multi": [
      "<MULTI>"
    ],
    "success_ec": "<SUCCESS_EC>",
    "mcc": "<MCC>",
    "recurrent": "<RECURRENT>",
    "card_on_file": "<CARD_ON_FILE>",
    "tid": "<TID>",
    "nsu": "<NSU>",
    "authorization_code": "<AUTHORIZATION_CODE>",
    "amount_cents": "<AMOUNT_CENTS>",
    "refunded_amount_cents": "<REFUNDED_AMOUNT_CENTS>",
    "cnpj": "<CNPJ>",
    "workspace_id": "<WORKSPACE_ID>",
    "account_id": "<ACCOUNT_ID>",
    "invoice_id": "<INVOICE_ID>",
    "client_ref": "<CLIENT_REF>",
    "credit_card_id": "<CREDIT_CARD_ID>",
    "currency": "<CURRENCY>",
    "installments": "<INSTALLMENTS>",
    "soft_descriptor": "<SOFT_DESCRIPTOR>",
    "created_at": "<CREATED_AT>",
    "updated_at": "<UPDATED_AT>",
    "transactions": [
      {
        "function": "<FUNCTION>",
        "success": "<SUCCESS>",
        "tid": "<TID>",
        "nsu": "<NSU>",
        "arp": "<ARP>",
        "acquirer": {
          "payment_id": "<PAYMENT_ID>",
          "status_code": "<STATUS_CODE>",
          "acquirer_mac_code": "<ACQUIRER_MAC_CODE>",
          "status_description": "<STATUS_DESCRIPTION>",
          "request_status_code": "<REQUEST_STATUS_CODE>",
          "request_status_description": "<REQUEST_STATUS_DESCRIPTION>"
        },
        "card_on_file": "<CARD_ON_FILE>",
        "amount_cents": "<AMOUNT_CENTS>",
        "commercial_enterprise": {
          "id": "<ID>",
          "name": "<NAME>",
          "number": "<NUMBER>",
          "acquirer": "<ACQUIRER>",
          "mcc": {
            "id": "<ID>",
            "code": "<CODE>",
            "description": "<DESCRIPTION>"
          }
        },
        "created_at": "<CREATED_AT>"
      }
    ],
    "anti_fraud": [
      {
        "id": "<ID>",
        "status": "<STATUS>",
        "score": "<SCORE>",
        "created_at": "<CREATED_AT>"
      }
    ]
  }
}

400

Requisição inválida. Possíveis causas: - `invalid_amount`: Valor zero ou negativo foi informado - `payment_cannot_be_canceled`: Pagamento não está em estado que permite cancelamento - `bad_request`: Erro genérico na requisição

error

String
Enum: `invalid_amount`, `payment_cannot_be_canceled`, `bad_request`

service

String

Nome do serviço que gerou o erro

Ex: Payments::CancelPolicyService

details Object Detalhes adicionais sobre o erro (varia por tipo)

Example

1
2
3
4
5
6
{
  "error": "<ERROR>",
  "service": "Payments::CancelPolicyService",
  "details": {
  }
}

401

Não autorizado - Token de autenticação inválido ou ausente

message

String

Ex: Bad credentials

Example

1
2
3
{
  "message": "Bad credentials"
}

404

Recurso não encontrado. Possíveis causas: - `payment_not_found`: Pagamento com o ID informado não existe - `payment_transaction_not_found`: Transação do pagamento não encontrada - `commercial_enterprise_not_found`: Estabelecimento comercial não encontrado - `payment_ref_not_found`: Referência do pagamento não encontrada - `credentials_not_found`: Credenciais do adquirente não configuradas

error

String
Enum: `payment_not_found`, `payment_transaction_not_found`, `commercial_enterprise_not_found`, `payment_ref_not_found`, `credentials_not_found`

service

String

Ex: Acquirers::CancelService

details Object

Example

1
2
3
4
5
6
{
  "error": "<ERROR>",
  "service": "Acquirers::CancelService",
  "details": {
  }
}

422

Erro de validação ou política. Possíveis causas: - `amount_not_permitted`: Valor solicitado excede o disponível para cancelamento - `authorization_cannot_be_partially_canceled`: Autorizações só podem ser canceladas totalmente - `cancellation_deadline_exceeded`: Prazo máximo para cancelamento foi excedido - `deny_getnet_D0_partial_refund`: Getnet não permite cancelamento parcial no mesmo dia (D0)

error

String
Enum: `payment_refunds_exausted`, `amount_not_permitted`, `authorization_cannot_be_partially_canceled`, `cancellation_deadline_exceeded`, `deny_getnet_D0_partial_refund`

service

String

Nome do serviço que gerou o erro

Ex: Payments::CancelPolicyService

details Object Detalhes adicionais (estrutura varia por tipo de erro)

Example

1
2
3
4
5
6
{
  "error": "<ERROR>",
  "service": "Payments::CancelPolicyService",
  "details": {
  }
}

429

Limite de taxa excedido Apenas 1 requisição de cancelamento por hora é permitida para cada payment_id.

error

String
Enum: `rate_limit_exceeded`

message

String

Ex: Rate limit exceeded. Try again later.

Example

1
2
3
4
{
  "error": "<ERROR>",
  "message": "Rate limit exceeded. Try again later."
}

500

Erro interno do servidor Erro inesperado durante o processamento. Entre em contato com o suporte se o problema persistir.

error

String

Tipo do erro interno

service

String

Serviço onde ocorreu o erro

details Object Detalhes do erro (quando disponível)

Example

1
2
3
4
5
6
{
  "error": "<ERROR>",
  "service": "<SERVICE>",
  "details": {
  }
}

Back

Autorizar e capturar em uma única requisição

Forward

Obter detalhes do pagamento